---
title: Annotation Models
description: Learn about the data structures used to represent PDF annotations in @embedpdf/engines.
searchable: true
---

# Annotation Models

All annotation-related methods in `@embedpdf/engines` use JavaScript objects that conform to the `PdfAnnotationObject` type definitions. These models can be imported directly from the `@embedpdf/models` package.

```typescript
import { PdfAnnotationObject, PdfHighlightAnnoObject, PdfAnnotationSubtype } from '@embedpdf/models';
````

## The Base Annotation Object

All annotation objects share a common set of base properties defined by the `PdfAnnotationObjectBase` interface.

| Property | Type | Description |
| :--- | :--- | :--- |
| **`id`** | `string` | A **unique UUID v4 identifier** for the annotation. This is crucial for updating and deleting. |
| **`type`** | `PdfAnnotationSubtype` | An enum value indicating the kind of annotation (e.g., `HIGHLIGHT`, `INK`, `FREETEXT`). |
| **`rect`** | `Rect` | The bounding box of the annotation on the page. |
| **`pageIndex`**| `number` | The 0-based index of the page this annotation belongs to. |
| **`contents`** | `string` | (Optional) The text content of the annotation, often used for comments. |
| **`author`** | `string` | (Optional) The author of the annotation. |
| **`modified`** | `Date` | (Optional) The date the annotation was last modified. |
| **`created`** | `Date` | (Optional) The date the annotation was created. |
| **`flags`** | `PdfAnnotationFlagName[]` | (Optional) An array of flags like `'print'`, `'noZoom'`, etc. |
| **`custom`** | `any` | (Optional) A field to store any custom JSON-serializable data. |

## Specific Annotation Types

Different types of annotations extend the base object with properties specific to their function.

### Markup Annotations

These annotations are used to mark up existing content on the page, typically text.

#### Highlight (`PdfHighlightAnnoObject`)

Used for highlighting text.

```typescript
export interface PdfHighlightAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.HIGHLIGHT;
  color: string;      // e.g., '#FFFF00'
  opacity: number;    // 0.0 to 1.0
  segmentRects: Rect[]; // An array of rectangles covering the highlighted text segments.
}
```

#### Underline (`PdfUnderlineAnnoObject`)

Used for underlining text.

```typescript
export interface PdfUnderlineAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.UNDERLINE;
  color: string;
  opacity: number;
  segmentRects: Rect[];
}
```

#### StrikeOut (`PdfStrikeOutAnnoObject`)

Used for striking through text.

```typescript
export interface PdfStrikeOutAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.STRIKEOUT;
  color: string;
  opacity: number;
  segmentRects: Rect[];
}
```

#### Squiggly (`PdfSquigglyAnnoObject`)

Used for applying a squiggly underline to text.

```typescript
export interface PdfSquigglyAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.SQUIGGLY;
  color: string;
  opacity: number;
  segmentRects: Rect[];
}
```

-----

### Shape & Drawing Annotations

These annotations add new vector shapes to the page.

#### Ink (`PdfInkAnnoObject`)

Used for freehand drawings.

```typescript
export interface PdfInkAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.INK;
  inkList: { points: { x: number; y: number }[] }[]; // Array of strokes, each with an array of points.
  strokeWidth: number; // The thickness of the ink strokes.
  color: string;       // The color of the ink, e.g., '#FF0000'.
  opacity: number;     // 0.0 to 1.0
}
```

#### Square (`PdfSquareAnnoObject`)

Used for drawing a square or rectangle.

```typescript
export interface PdfSquareAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.SQUARE;
  color: string; // Fill color
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}
```

#### Circle (`PdfCircleAnnoObject`)

Used for drawing a circle or ellipse.

```typescript
export interface PdfCircleAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.CIRCLE;
  color: string; // Fill color
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}
```

#### Line (`PdfLineAnnoObject`)

Used for drawing a single straight line.

```typescript
export interface PdfLineAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.LINE;
  linePoints: { start: Position; end: Position };
  lineEndings?: { start: PdfAnnotationLineEnding; end: PdfAnnotationLineEnding };
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}
```

#### Polyline (`PdfPolylineAnnoObject`)

Used for drawing a series of connected line segments.

```typescript
export interface PdfPolylineAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.POLYLINE;
  vertices: Position[];
  lineEndings?: { start: PdfAnnotationLineEnding; end: PdfAnnotationLineEnding };
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}
```

#### Polygon (`PdfPolygonAnnoObject`)

Used for drawing a closed, multi-sided shape.

```typescript
export interface PdfPolygonAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.POLYGON;
  vertices: Position[];
  color: string; // Fill color
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}
```

-----

### Text-Based Annotations

#### FreeText (`PdfFreeTextAnnoObject`)

Used for "Typewriter" style text boxes placed anywhere on the page.

```typescript
export interface PdfFreeTextAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.FREETEXT;
  contents: string;
  fontSize: number;
  fontColor: string; // e.g., '#000000'
  fontFamily: PdfStandardFont;
  textAlign: PdfTextAlignment; // Left, Center, or Right
  backgroundColor?: string;
  opacity: number;
}
```

#### Text (`PdfTextAnnoObject`)

Used for "Sticky Note" style comments that appear as an icon on the page and reveal text when opened.

```typescript
export interface PdfTextAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.TEXT;
  contents: string;
  color?: string;
  opacity?: number;
  icon?: PdfAnnotationIcon;
  state?: PdfAnnotationState;
  stateModel?: PdfAnnotationStateModel;
}
```

-----

### Other Annotation Types

#### Stamp (`PdfStampAnnoObject`)

Used for applying an image or predefined text stamp (e.g., "APPROVED"). The visual content for a new stamp is provided via the `context` parameter in `createPageAnnotation`.

```typescript
export interface PdfStampAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.STAMP;
}
```